Workshop 1 - Getting Familiar with GitHub
There are many ways to do the same thing in GitHub, we will give you our favourite (easy + fast), but you can explore others if you want.
Repository: One project. It can contain
multiple scripts and data sets.
Clone: Copy a repository to your computer so
you can work on it.
Template: A repository that contains useful
code. You can clone it and modify it for your own project. Even if you
clone a repository, the changes will not affect the original.
Push: Upload your change sin GitHub.
Pull: Download any changes you (or anybody
else) did in a repository you have already cloned. i.e. Download form
the internet to your computer.
Open GitHub desktop and click sign in to GitHub.com:
Then, introduce your log in details if the app asks for them (if you are already logged in in your browser, the app would probably fill everything automatically). Then, authorize the application to open with GitHub Desktop.
The following window will pop up:
click finish
Once you have completed these steps, send your GitHub username and email address to amandaf@unimelb.edu.au so that we can invite you the lab organization: “bugoftheweek”.
Upload a repository that you created on your own GitHub account.
This scenario will be useful if you already have a project for one of your papers and want to share your code with the world.
Go to R studio and assign a project to your script Note: You may have already assigned a project, if at the beginning, you started by creating a new project instead of just a new script.
In the upper right corner click in the arrow to display the dropdown menu. Click on “New Project”.
Follow the prompts: New directory – New Project -Add name and location
Note: Do not select “create a git repository”. It is possible to do it this way, but it is longer. And click “Accept”.
Create a new repository from GitHub Desktop
Open GitHub Desktop
Both paths will lead to this pop up
Choose the directory where you have your project. And click on “create repository”. Then this windwo will appear
Next, your app would look like this
Click publish repository, and that is it! It will be uploaded to your GitHub.
Push your local changes to GitHub
Any time you make changes in your code in your local folder, they will appear on the left-hand panel. When you are ready, write a small summary and description of your changes so that people know why this was required and then push them to GitHub by selecting “Commit to main”
Next, your app would look like this
Continue working on your file
From now on, it will be super easy to upload your local changes to your GitHub.com. Just hit “commit to main” after you are happy with your changes.
Important!!! Always pull origin before start working on any repository. In this way you first download the latest version online, then combine that with your local changes. Here is an example:
Always click “fetch origin” before making any changes in your local file.
After clicking “fetch origin”, the desktop app detected that there were two changes online, so you need to select “Pull origin” and then work on that last version.
This is a parenthesis for troubleshooting
It can happen that you and your collaborator worked on the file at the same time. In this case, you would need to commit your changes, then pull and then resolve the mismatches selecting what to keep. However, this is a bit more complicated. One option is to type this line in your console:
GitHub Desktop will ask you if you want to open with R. Say yes, and it will show you the conflicts.
Resolve the conflicts, save the file and push to your GitHub. Hopefully that is not necessary
End of troubleshooting
Click on “Fetch Origin” and then “History” to see the changes from your collaborators or the ones you did on your GitHub.com
And when you open the file in your computer you can be sure all the merging has been done automatically and your file has all the remote changes already included. 😊
Use a template repository from “bugoftheweek”
This scenario will be useful if you are new to a topic and want to use already existent code to apply to your project. We have got your back!
Got to your GitHub.com. By this time you probably have been added to “bugoftheweek”. On the left-hand panel, under your profile photo, find the title “Organizations” and click on the picture. We have divided the repositories according to your topics of interest. Click on the one you need, and then click on the button “Use this template”.
You will see this screen
(Note: this is an example from another repository, Statistics) Make sure you change the “owner” to your own username. Add a name for this repository and click “Create repository from template”
Clone this template to work on it from your computer
Go to GitHub desktop. Select File - Clone repository - Select the one you want to work on and indicate the folder on your computer where you want to send it to.
For this example, notice that this repository is already on my GitHub since it has my username/the name I gave it. This ensures that when you clone a template you won’t modify the original. That’s it! Now it is all yours. You can start working on it normally, and when you are happy with your changes you can commit to main and it will be saved in your GitHub.com. It will be saved as a public file which is great to share your code with reviewers or peer scientists.
Modify a template repository and upload to “bugoftheweek”
This scenario will be useful if you realize you want to contribute to our common knowledge and produce more templates for your fellow lab-mates.
Before doing this, please discuss with Amanda. Ideally, we do not want to change the templates too much, only when we identify there is a mistake that needs to be amended, or we want to add a new script.
Clone the template from the organization to work on it from your computer
Go to GitHub desktop. Select File - Clone repository - Select the one you want to work on and indicate the folder on your computer where you want to send it to.
Notice that in this case, the repository still belongs to “bugoftheweek”. Select the folder you want to save it to.
Work on the scripts normally and then push your changes by selecting “commit to main”. The original template will be updated.
Annnnnd this is how we conclude this brief introduction to GitHub.
We hope you find it useful!